.\" Copyright (c) 2013 Sebastian Kuzminsky
.\" derived from the vfs11_vfd manpage by Michael Haberler and John Thornton
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
.\" USA.
.\"
.\" $Id: vfdb_vfd.1,v 1.8 2009-09-19 13:49:34 mah Exp $
.\"
.TH vfdb_vfd "1" "September 19, 2009" "VFD-B VFD" "LinuxCNC Documentation"

.SH NAME
\fBvfdb_vfd\fR - HAL userspace component for Delta VFD-B Variable Frequency Drives

.SH SYNOPSIS
.B vfdb_vfd
.RI [OPTIONS]
.br

.SH DESCRIPTION
This manual page explains the
.B vfdb_vfd
component. This component reads and writes to the VFD-B device via a
Modbus connection.
.PP
\fBvfdb_vfd\fP is for use with LinuxCNC.

.SH QUICK START
The VFD-B ships in a configuration that can not talk to this driver.
The VFD-B must be reconfigured via the face plate by the integrator
before it will work.  This section gives a brief description of what
changes need to be made, consult your Delta VFD-B manual for more details.
.RS
.TP
Switch the VFD-B to Modbus RTU frame format:
Switch parameter 09-04 from the factory default of 0 (Ascii framing)
to 3, 4, or 5 (RTU framing).  The setting you choose will determine
several serial parameters in addition to the Modbus framing protocol.
.TP
Set the frequency control source to be Modbus, not the keypad:
Switch parameter 02-00 from factory default of 00 (keypad control) to 5
(control from RS-485).
.TP
Set the run/stop control source to be Modbus, not the keypad:
Switch parameter 02-01 from the factory default of 0 (control from keypad)
to 3 (control from Modbus, with Stop enabled on the keypad).
.RE

.SH OPTIONS
.B
.IP \-n\ \-\-name\ <halname>
set the HAL component name
.B
.IP \-d\ \-\-debug
Turn on debugging messages. Also toggled by sending a USR1 signal to the
vfdb_vfd process.
.B
.IP \-m\ \-\-modbus\-debug
Turn on Modbus debugging messages. This will cause all Modbus messages to
be printed in hex on the terminal.  Also toggled by sending a USR2 signal
to the vfdb_vfd process.
.B
.IP \-I\ \-\-ini\ <inifilename>
take configuration from this ini
file. Defaults to environment variable INI_FILE_NAME.  Most vfdb_vfd
configuration comes from the ini file, not from command-line arguments.
.B
.IP \-S\ \-\-section\ <section\ name>
take configuration from this
section in the ini file. Defaults to 'VFD-B'.
.B
.IP \-r\ \-\-report\-device
report device propertiers on console at startup

.SH INI CONFIG VARIABLES
.B
.IP DEBUG
Set to a non-zero value to enable general debug output from the VFD-B
driver.  Optional.
.B
.IP MODBUS_DEBUG
Set to a non-zero value to enable modbus debug output from the VFD-B
driver.  Optional.
.B
.IP DEVICE
Serial port device file to use for Modbus communication with the VFD-B.
Defaults to '/dev/ttyS0'.
.B
.IP BAUD
Modbus baud rate.  Defaults to 19200.
.B
.IP BITS
Modbus data bits.  Defaults to 8.
.B
.IP PARITY
Modbus parity.  Defaults to Even.  Accepts 'Even', 'Odd', or 'None'.
.B
.IP STOPBITS
Modbus stop bits.  Defaults to 1.
.B
.IP TARGET
Modbus target number of the VFD-B to speak to.  Defaults to 1.
.B
.IP POLLCYCLES
Only read the less important variables from the VFD-B once in this many
poll cycles.  Defaults to 10.
.B
.IP RECONNECT_DELAY
If the connection to the VFD-B is broken, wait this many seconds before
reconnecting.  Defaults to 1.
.B
.IP MOTOR_HZ,\ MOTOR_RPM
The frequency of the motor (in Hz) and the corresponding speed of the
motor (in RPM).  This information is provided by the motor manufacturer,
and is generally printed on the motor's name plate.

.SH PINS
.B
.IP <name>.at\-speed\ (bit,\ out)
True when drive is at commanded speed (see
.I
speed\-tolerance
below)
.B
.IP <name>.enable\ (bit,\ in)
Enable the VFD. If False, all operating parameters are still read but
control is released and panel control is enabled (subject to VFD setup).
.B
.IP <name>.frequency\-command\ (float,\ out)
Current target frequency in HZ as set through speed\-command (which is in
RPM), from the VFD.
.B
.IP <name>.frequency\-out\ (float,\ out)
Current output frequency of the VFD.
.B
.IP <name>.inverter\-load\-percentage\ (float,\ out)
Current load report from VFD.
.B
.IP <name>.is\-e\-stopped\ (bit,\ out)
The VFD is in emergency stop status (blinking "E" on panel).
.B
.IP <name>.is\-stopped\ (bit,\ out)
True when the VFD reports 0 Hz output.
.B
.IP <name>.jog\-mode\ (bit,\ in)
1 for ON and 0 for OFF, enables the VFD-B 'jog mode'. Speed control
is disabled.  This might be useful for spindle orientation.
.B
.IP <name>.max\-rpm\ (float,\ out)
Actual RPM limit based on maximum frequency the VFD may generate, and
the motors nameplate values. For instance, if
.I nameplate\-HZ
is 50, and
.I nameplate\-RPM
is 1410, but the VFD may generate up to 80Hz, then
.I max\-rpm
would read as 2256 (80*1410/50). The frequency limit is read from the VFD
at startup.  To increase the upper frequency limit, the UL and FH
parameters must be changed on the panel.  See the VFD-B manual for
instructions how to set the maximum frequency.
.B
.IP <name>.modbus\-ok\ (bit,\ out)
True when the Modbus session is successfully established and the last 10
transactions returned without error.
.B
.IP <name>.motor\-RPM\ (float,\ out)
Estimated current RPM value, from the VFD.
.B
.IP <name>.motor\-RPS\ (float,\ out)
Estimated current RPS value, from the VFD.
.B
.IP <name>.output\-voltage\ (float,\ out)
From the VFD.
.B
.IP <name>.output\-current\ (float,\ out)
From the VFD.
.B
.IP <name>.speed\-command\ (float,\ in)
Speed sent to VFD in RPM. It is an error to send a speed faster than the
Motor Max RPM as set in the VFD.
.B
.IP <name>.spindle\-on\ (bit,\ in)
1 for ON and 0 for OFF sent to VFD, only on when running.
.B
.IP <name>.max\-speed\ (bit,\ in)
Ignore the loop-time parameter and run Modbus at maximum
speed, at the expense of higher CPU usage. Suggested use
during spindle positioning.
.B
.IP <name>.status\ (s32,\ out)
Drive Status of the VFD (see the VFD manual). A bitmap.
.B
.IP <name>.error\-count\ (s32,\ out)
Total number of transactions returning a Modbus error.
.B
.IP <name>.error\-code\ (s32,\ out)
Most recent Error Code from VFD.
.B
.IP <name>.frequency\-limit\ (float,\ out)
Upper limit read from VFD setup.
.B

.SH PARAMETERS
.B
.IP <name>.loop\-time\ (float,\ RW)
How often the Modbus is polled (default interval 0.1 seconds).
.B
.IP <name>.nameplate\-HZ\ (float,\ RW)
Nameplate Hz of motor (default 50). Used to calculate target frequency
(together with
.I nameplate\-RPM
) for a target RPM value as given by speed\-command.
.B
.IP <name>.nameplate\-RPM\ (float,\ RW)
Nameplate RPM of motor (default 1410)
.B
.IP <name>.rpm\-limit\ (float,\ RW)
Do-not-exceed soft limit for motor RPM (defaults to
.I nameplate\-RPM
).
.B
.IP <name>.tolerance\ (float,\ RW)
Speed tolerance (default 0.01) for determining wether spindle is at speed
(0.01 meaning: output frequency is within 1% of target frequency).

.SH USAGE
The vfdb_vfd driver takes precedence over panel control while it is enabled
(see
.I .enable
pin), effectively disabling the panel. Clearing the
.I .enable
pin re-enables the panel. Pins and parameters can still be set, but will
not be written to the VFD untile the .enable pin is set. Operating
parameters are still read while bus control is disabled.
.P
Exiting the vfdb_vfd driver in a controlled way will release the VFD from
the bus and restore panel control.

See the LinuxCNC Integrators Manual for more information. For a detailed
register description of the Delta VFD-B, see the VFD manual.


.SH AUTHOR
Yishin Li; based on vfd11_vfd by Michael Haberler.
.SH LICENSE
GPL
